前後端分離下，常用 API 當作溝通橋樑的專案，一個專案 API 數量可能非常多支，以我的團購功能來說，新增團購、檢視團購、修改團購、刪除團購 就已經四支 API 了，再加上產品功能、購物車功能、訂單功能，一個小小的專案可能就有二十個以上的 API 。

這樣的情況下，後端工程師勢必會需要跟專案 PM 、前端工程師溝通，而工程師的時間都很寶貴，有效的溝通對於 PM 、前端工程師來說都是幫助，此時就很需要良好的 API 文件！

API 文件是什麼？

API 文件介紹

API文件（Application Programming Interface documentation）是一種技術文件，提供每支 API 的詳細內容和指南。API 是一種用於不同軟體或系統之間進行溝通和互相操作的方式。

API 文件可以以不同的格式提供，包括 HTML 網頁、PDF 檔案、Markdown 文件、Swagger 或OpenAPI 規範、以及在開發工具中的集成幫助。這些文件的目標是使開發人員能夠有效地使用 API，並為他們提供必要的信息，以實現應用程序的互操作性和功能。

什麼專案需要 API 文件？

1. 前後端分離專案

   需要 API 文件讓前端工程師可以串 API，使用者操作時按下按鈕 = 打API，並讓收到的結果顯示於畫面上正確位置

2. 提供其他開發者介接系統的專案：

   許多軟體系統間會互相串連，以提供此用者更好的使用體驗。例如常見的：第三方登入、金流系統、直接連到 google map 等等，這類系統間的串接，就是使用 API 取得另一個系統的資料，如果要串接該服務，就要去那個系統找尋提供給開發人員的 API 文件尋找打 API 的方法、提供正確的參數訊息，才會拿到所需要的資料。

什麼是 OpenAPI 規範 ( OAS 標準 )？

當每個專案都需要 API 文件，每個程式語言、不同開發者、不同公司都有自己一套的 API 撰寫方式時，要閱讀別人的 API 文件就變得有點困難。

為了解決這個問題，國際 Open API Initiative (OAI) 組織制定 OpenAPI Specification (OAS) 標準，定義 API 文件應有的格式規範，提供開發人員參考、比照撰寫 API 文件，依循此標準撰寫的 API 文件會比較好讓開發者閱讀。

當然這只是開放標準，也就是即便你不想遵守也毫無問題。只是如果遵守此規範，會較為容易幫助其他開發者取用 API 資料。

這個 PDF 檔案寫得滿好的，推薦閱讀：API標準化與OAS規範介紹

來看兩個 API 文件範例

以下是我覺得寫得不錯的、跟好想後端小 mentor (a.k.a 好想小帥)覺得不錯的 API 文件

綠界科技全方位金流 API 技術文件：https://developers.ecpay.com.tw/?p=2862

Notion API Reference：https://developers.notion.com/reference/post-page

剛好中文文件對照英文文件，各位應該可以很輕易分辨吧～

API 描述

對API的簡要概述，包括其功能、用途和重要性。

端點和請求(Endpoints and Requests)

詳細描述 API 的各個端點（也稱為路由）以及可用的HTTP請求方法（如GET、POST、PUT、DELETE等）。這部分通常會包括端點的 URL 和所需的請求參數。

notion:

參數(Parameters)

對請求參數的描述，包括每個參數的名稱、類型、是否必填以及範例。

響應(Responses) 與 範例(Examples)

對 API 響應的描述，包括成功響應的格式和可能的錯誤響應。這通常包括 HTTP 狀態碼和相關的錯誤消息。

綠界只有回傳參數說明，沒有實際範例

notion 則包含各種回應範例，但沒有針對回傳的參數進一步描述

curl 'https://api.notion.com/v1/pages' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  --data '{
	"parent": { "database_id": "d9824bdc84454327be8b5b47500af6ce" },
  "icon": {
  	"emoji": "🥬"
  },
	"cover": {
		"external": {
			"url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
		}
	},
// ...

身份驗證和授權(Authentication and Authorization)

如果API需要身份驗證或授權，則文件通常會提供相關信息，例如需要 API 金鑰、token 或 OAuth 流程。
綠界因為是金流系統，針對驗證方式有詳細說明

notion 只要請求有帶 token

版本控制(Versioning)

如果 API 具有多個版本，則文件通常會指示如何指定所需的 API 版本。
綠界寫在介接網址裡面：

notion則直接寫在請求裡面：

除上述外， API 文件可能還會包括以下內容：

• 限制和配額(Rate Limits and Quotas)：關於API的使用限制、速率限制和配額的信息。
• 安全性(Security)：有關API的安全性實踐、建議和最佳實踐的信息。
• 常見問題和疑難解答：對開發人員可能遇到的常見問題和問題的解答。

今天用很多圖介紹 API 文件，下一篇來介紹好用的 API 文件軟體！